Choosing File Objects

Navigation Services provides functions that prompt the user to select file objects (files, folders, or volumes) or create a new folder.

Choosing a File

The function NavChooseFile displays a dialog box that prompts the user to choose a file for some action other than opening. The file could be a preference file, dictionary, or other specialized file. Figure 11 shows an example of this dialog box.

Figure 11 Choose a File dialog box

Since this is a simplified function, no built-in translation is available and no Show menu is available. By default, Navigation Services performs no filtering on the files it displays in the browser list. You need to provide file types in the typeList parameter or implement an application-defined filter function if you want to affect the file types displayed in the browser list. The NavChooseFile function ignores the signature field of the NavTypeList structure, so all files of the types specified in the typeList parameter will be shown, regardless of their application signature. For more information on filtering options, see Filtering File Objects.

You can provide a message or "banner" in the Choose File dialog box by supplying a string in the message field of the structure of type NavDialogOptions that you pass in the dialogOptions parameter of the NavChooseFile function. This string is displayed below the browser list. If you do not supply a string, no message is displayed.

Choosing a Folder

The function NavChooseFolder displays a dialog box that prompts the user to choose a folder, as shown in Figure 12 . This could be useful when performing installations, for example.

Figure 12 Choose a Folder dialog box

The browser list in a Choose a Folder dialog box displays folders and volumes only.

One possible source of confusion to users who wish to use keyboard equivalents in a list-based file system browser is the purpose of the Enter or Return keys: do they select a folder or do they open it? Navigation Services resolves this issue by mapping the Return and Enter keys to the Open button, which is used to navigate into folders. After navigating to the desired location, the user clicks the Choose button to select the folder.

Note

If the user navigates to the desktop, deselects the current selection by shift-clicking and presses the Choose button, NavChooseFolder identifies the desktop as the folder chosen.

You can provide a message or "banner" in the Choose a Folder dialog box by supplying a string in the message field of the structure of type NavDialogOptions that you pass in the dialogOptions parameter of the NavChooseFolder function. This string is displayed below the browser list. In Figure 12 , for example, the application supplies the string, "Please select a folder." If you do not supply a string, no message is displayed.

Choosing a Volume

The function NavChooseVolume displays a dialog box that prompts the user to choose a volume, as shown in Figure 13 .

Figure 13 Choose a Volume dialog box

This function is useful when you want the user to select a volume or storage device.

You can provide a message or "banner" in the Choose a Volume dialog box by supplying a string in the message field of the structure of type NavDialogOptions that you pass in the dialogOptions parameter of the NavChooseVolume function. This string is displayed below the browser list. For example, a disk repair utility might supply a message like "Please choose a volume to repair." If you do not supply a string, no message is displayed.

Choosing a File Object

The function NavChooseObject displays a dialog box that prompts the user to select a file object, as shown in Figure 14 .

Figure 14 Choose Object dialog box

This function is useful when you need the user to select an object that might be one of several different types. If you need to have the user select an object of a specific type, you should use the function appropriate to that type. For example, if you know the object is a file, use the function NavChooseFile .

Note

The NavChooseObject function does not allow the user to choose zones or servers.

You can provide a message or "banner" in the Choose Object dialog box by supplying a string in the message field of the structure of type NavDialogOptions that you pass in the dialogOptions parameter of the NavChooseObject function. This string is displayed below the browser list. In Figure 14 , for example, the application supplies the string, "Please choose a file object." If you do not supply a string, no message is displayed.

Creating a New Folder

The function NavNewFolder displays a dialog box that prompts the user to create a new folder, as shown in Figure 15 .

Figure 15 New Folder dialog box

You can provide a message or "banner" in the New Folder dialog box by supplying a string in the message field of the structure of type NavDialogOptions that you pass in the dialogOptions parameter of the NavNewFolder function. This string is displayed below the browser list. For example, the Sampler installer might provide a message like "Create a folder to install Sampler." If you do not supply a string, no message is displayed.